[![](https://dcbadge.vercel.app/api/server/3E8ca2dkcC)](https://discord.gg/osmu)

![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/bitaxeorg/esp-miner/total)
![GitHub commit activity](https://img.shields.io/github/commit-activity/t/bitaxeorg/esp-miner)
![GitHub contributors](https://img.shields.io/github/contributors/bitaxeorg/esp-miner)


# BluAX
BluAX is open source ESP32 firmware modified based on the [Bitaxe](https://github.com/bitaxeorg/bitaxe)

You can purchase one on our [website](https://bluax.digitalshovel.com) and find the set up instruction [here](https://digitalshovel.com/BluAX-instructions.html).

# Bitaxetool
Bitaxe has a command line python tool for flashing BluAX and updating the config called Bitaxetool 

**Bitaxetool Requires Python3.4 or later and pip**

Install bitaxetool from pip. pip is included with Python 3.4 but if you need to install it check <https://pip.pypa.io/en/stable/installation/>

```
pip install --upgrade bitaxetool
```
The bitaxetool includes all necessary library for flashing the binaries to the BluAX Hardware.

- Flash a "factory" image to a BluAX to reset to factory settings. Make sure to choose an image built for your hardware version (320) in this case:

```
bitaxetool --firmware ./esp-miner.bin
```
- Flash just the NVS config to a BluAX:

```
bitaxetool --config ./config-320.cvs
```
- Flash both a factory image _and_ a config to your BluAX: note the settings in the config file will overwrite the config already baked into the factory image:

```
bitaxetool --config ./config-320.cvs --firmware ./esp-miner.bin
```

## AxeOS API
The esp-miner UI is called AxeOS and provides an API to expose actions and information.

For more details take a look at [`main/http_server/openapi.yaml`](./main/http_server/openapi.yaml).

Things that can be done are:
  
  - Get System Info
  - Get System Statistics
  - Update Swarm
  - System Restart Action
  - Update System Settings Action
  - System Options
  - Update OTA Firmware
  - Update OTA WWW
  - Logs over WebSocket

Some API examples in curl:
  ```bash
  # Get system information
  curl http://YOUR-BLUAX-IP/api/system/info
  ```
  ```bash
  # Get system statistics
  curl http://YOUR-BLUAX-IP/api/system/statistics
  ```
  ```bash
  # System restart action
  curl -X POST http://YOUR-BLUAX-IP/api/system/restart
  ```

## Administration

The firmware hosts a small web server on port 80 for administrative purposes. Once the BluAX device is connected to the local network, the admin web front end may be accessed via a web browser connected to the same network at `http://<IP>`, replacing `IP` with the LAN IP address of the BluAX device, provided your network supports mDNS configuration.

### Recovery

In the event that the admin web front end is inaccessible, for example because of an unsuccessful firmware update (`www.bin`), a recovery page can be accessed at `http://<IP>/recovery`.

### Unlock Settings

In order to unlock the Input fields for ASIC Frequency and ASIC Core Voltage you need to append `?oc` to the end of the settings tab URL in your browser. Be aware that without additional cooling overclocking can overheat and/or damage your BluAX.

## Development

### Prerequisites

- Install the ESP-IDF toolchain from https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/
- Install nodejs/npm from https://nodejs.org/en/download
- (Optional) Install the ESP-IDF extension for VSCode from https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension

### Building

At the root of the repository, run:
```
idf.py build && ./merge_bin.sh ./esp-miner-merged.bin
```

Note: the merge_bin.sh script is a custom script that merges the bootloader, partition table, and the application binary into a single file.

Note: if using VSCode, you may have to configure the settings.json file to match your esp hardware version. For example, if your BluAX has something other than an esp32-s3, you will need to change the version in the `.vscode/settings.json` file.

### Flashing

With the BluAX connected to your computer via USB, run:

```
bitaxetool --config ./config-xxx.cvs --firmware ./esp-miner-merged.bin
```

where xxx is the config file for your hardware version. You can see the list of available config files in the root of the repository.

A custom board version is also possible with `config-custom.cvs`. A custom board needs to be based on an existing `devicemodel` and `asicmodel`.

Note: if you are developing within a dev container, you will need to run the bitaxetool command from outside the container. Otherwise, you will get an error about the device not being found.

## Attributions

The display font is Portfolio 6x8 from https://int10h.org/oldschool-pc-fonts/ by VileR.
